Micron Document
Fox's Git Mirrors

Node / rns-mirrors / Reticulum-Go.git / files / docs / en / api-reference.md

Displaying Rendered • View raw • Download

docs/en/api-reference.md 633735d797cc5f5d48cb2e22e8fd7cd743930daf (633735d7) Text, 18.16 KB

API reference

This is the application-facing API guide for Reticulum-Go. It is not a dump of every exported symbol. It is organized the way you build programs: choose an integration path, follow a recipe, then look up types and methods.

Wire behavior matches the Python RNS API reference. Package layout, concurrency rules, and embedder lifecycle are Go-specific and documented here because the Python manual does not cover them.

For generated signatures, use T383838go doc on the import path or browse the module on pkg.go.dev. For package file maps, see Package map.

How this differs from the Python reference

┌─────────────────────────────────────────────────────────┬────────────────────────────────────────┐
│ Python RNS manual │ This document │
├─────────────────────────────────────────────────────────┼────────────────────────────────────────┤
│ Class catalog (T383838RNS.Reticulum, Identity, Destination, …) │ Task-first recipes, then API tables │
│ One process model (T383838RNS.Reticulum(...)) │ Four integration paths with trade-offs │
│ Little concurrency guidance │ Explicit callback and locking rules │
│ No C / WASM / control-plane docs in the same place │ Links to Control API, librns, WASM │
│ Examples live elsewhere │ Recipes point at T383838examples/ │
└─────────────────────────────────────────────────────────┴────────────────────────────────────────┘

Choose an integration path

T282828
Need Reticulum in my app
|
v
Go process?
/ \\
yes no
| |
v v
pkg/node Same machine as daemon?
in-process |
-------+-------
/ | \\
yes C/FFI browser
| | |
v v v
Control API librns pkg/wasm
HTTP/WS .so
\\ | /
\\ | /
v v v
destination + link

┌───────────────────────────────┬────────────┬─────────────────────────────────────────────────────┐
│ Path │ Package /… │ Use when │
├───────────────────────────────┼────────────┼─────────────────────────────────────────────────────┤
│ In-process Go │ T383838pkg/node │ Default for Go services and tools │
│ Daemon + JSON │ Control.

Recipe: inbound link and request handler

T282828
dest.AcceptsLinks(true)
dest.SetLinkEstablishedCallback(func(v any) {
l := v.(*link.Link) // import pkg/link
_ = l.SetResourceStrategy(link.AcceptAll)
l.SetPacketCallback(func(data []byte, _ *packet.Packet) {
log.Printf("data: %q", data)
})
})

_ = dest.RegisterRequestHandler("/echo",
func(_ string, data []byte, _ []byte, _ []byte, _ *identity.Identity, _ int64) []byte {
return data
},
destination.AllowAll, nil)

Recipe: outbound link and request

T282828
remoteID, err := identity.Recall(peerDestHash)
if err != nil {
log.Fatal(err)
}
out, err := destination.FromHash(peerDestHash, remoteID, destination.Single, n.Transport())
if err != nil {
log.Fatal(err)
}
if !n.Transport().HasPath(peerDestHash) {
_ = n.Transport().RequestPath(peerDestHash, "", nil, false)
ctx, cancel := context.WithTimeout(context.Background(), rnsutil.PathResponseWindow(n.Transport(), peerDestHash))
defer cancel()
if err := rnsutil.WaitPath(ctx, n.Transport(), peerDestHash); err != nil {
log.Fatal(err)
}
}
l := link.NewLink(out, n.Transport(), nil, nil, nil)
if err := l.Establish(); err != nil {
log.Fatal(err)
}
receipt, err := l.Request("/echo", []byte("ping"), 15*time.Second)
if err != nil {
log.Fatal(err)
}
// poll receipt.Concluded() or set receipt.SetResponseCallback

Recipe: send a file resource

T282828
res, err := resource.New(fileBytes, true)
if err != nil {
log.Fatal(err)
}
_ = res.SetMetadata(map[string]any{"name": []byte("report.bin")})
if err := l.SendResource(res); err != nil {
log.Fatal(err)
}

On the receiver, set AcceptAll or AcceptApp and handle T383838link.IncomingResource (or plain T383838[]byte when no metadata). CLI equivalent: rgocp in CLI utilities.

Recipe: network sleep and wake

T282828
n.SetPauseMode(node.PauseModeDisable)
_ = n.OnNetworkLost() // pause links, disable interfaces
_ = n.OnNetworkAvailable()
_ = n.RefreshPaths() // re-request watched destinations

Optional: T383838n.EnableLinkAutoReconnect(node.LinkReconnectOptions{MaxAttempts: 5, Backoff: time.Second}) and T383838n.RegisterLink(l).

Core types

Node (T383838pkg/node)

Orchestrates transport, interfaces, shared instance, and lifecycle. Prefer this over constructing T383838transport.Transport by hand.


┌─────────────────────────────────────┬────────────────────────────────────────────────────────────┐
│ Symbol │ Role │
├─────────────────────────────────────┼────────────────────────────────────────────────────────────┤
│ T383838New(cfg) (*Node, error) │ Build without starting │
│ T383838Start() error │ Transport, path handler, shared instance, interfaces │
│ T383838Stop() error │ Tear down in reverse order │
│ T383838Transport() *transport.Transport │ Pass to destinations and links │
│ T383838Config() *common.ReticulumConfig │ Active config │
│ T383838Interfaces() []interfaces.Interface │ Configured interfaces │
│ T383838OnNetworkAvailable() error │ Resume after outage │
│ T383838OnNetworkLost() error │ Pause for sleep / NIC down │
│ T383838SetPauseMode(PauseMode) │ PauseModeDisable or PauseModeStop │
│ T383838WatchDestination(hash) │ Include hash in wake refreshes │
│ T383838RefreshPaths(dests...) │ Force path refresh │
│ T383838ReloadInterfaces(newCfg) │ Hot-reload interface blocks │
│ T383838EnableLinkAutoReconnect(opts) │ Re-establish registered links │
│ T383838RegisterLink(l) │ Track link for reconnect │
│ T383838StartInterfaceDiscovery() │ rnstransport discovery listen + InterfaceAnnouncer when d… │
└─────────────────────────────────────┴────────────────────────────────────────────────────────────┘

Identity (T383838pkg/identity)

┌─────────────────────────────────────────────────────┬────────────────────────────────────────────┐
│ Symbol │ Role │
├─────────────────────────────────────────────────────┼────────────────────────────────────────────┤
│ T383838New() (*Identity, error) │ Generate software identity (preferred) │
│ T383838NewIdentity() │ Alternate generator │
│ FromFile / ToFile │ Persist via identity_backend (file, Secre… │
│ FromBytes / FromPublicKey │ Load from bytes │
│ T383838LoadIdentityFile(path, signer) │ Software or RHB1 hardware-bound (also res… │
│ T383838NewIdentityWithSigner(...) │ External Ed25519 signer (HSM) │
│ SetIdentityBackend / ApplyIdentityBackendFromConfig │ Select file or secretservice │
│ Close / Wipe │ Zero locked private key buffers │
│ T383838Hash() []byte │ 16-byte truncated hash │
│ T383838GetPublicKey() []byte │ 64-byte combined public key │
│ Sign / Verify │ Ed25519 │
│ Encrypt / Decrypt │ Identity tokens with optional ratchets │
│ RememberRatchet / GetRatchet / CurrentRatchetID │ Announced peer ratchet public keys │
│ T383838Recall(destHash) │ Public identity from known destinations │
│ Remember / ValidateAnnounce │ Announce storage │
│ LoadOrCreateTransportIdentity │ Daemon transport identity │
│ RotateRatchet / GetRatchets / GetCurrentRatchetKey │ Explicit identity-level keys only. Does n… │
└─────────────────────────────────────────────────────┴────────────────────────────────────────────┘

Constants: KeySize (bits), TruncatedHashLength (bits). Hex destination or identity hashes are 32 characters.

Private key material uses T383838pkg/securemem (best-effort mlock, wipe on Close). See Identity and destinations.

Destination (T383838pkg/destination)

┌──────────────────────────────────┬───────────────────────────────────────┐
│ Constant │ Meaning │
├──────────────────────────────────┼───────────────────────────────────────┤
│ In / Out │ Direction bit flags (T383838In|Out for both) │
│ Single / Group / Plain │ Destination types │
│ ProveNone / ProveAll / ProveApp │ Proof strategy │
│ AllowNone / AllowAll / AllowList │ Request handler ACL │
└──────────────────────────────────┴───────────────────────────────────────┘

┌────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
│ Symbol │ Role │
├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ T383838New(id, direction, type, app, transpo… │ Create and optionally auto-register (In) │
│ T383838FromHash(hash, id, type, transport) │ Outbound destination for a known peer │
│ T383838Hash(id, app, aspects...) │ Compute destination hash │
│ ParseName / ExpandAppName │ Dotted name helpers │
│ T383838Announce(pathResponse, tag, iface) │ Publish reachability │
│ T383838AcceptsLinks(bool) │ Accept link requests │
│ Encrypt / Decrypt / Sign │ Destination crypto │
│ CreateKeys / LoadPrivateKey / GetPriv… │ GROUP Token PSK (64-byte AES-256 default) │
│ SetPacketCallback │ Single-packet inbound data │
│ SetLinkEstablishedCallback │ Inbound link ready (T383838func(any)) │
│ RegisterRequestHandler / RegisterRequ… │ Link request paths │
│ EnableRatchets(path) │ Enable SINGLE ratchets and persist private keys at path │
│ EnableRatchetsInMemory │ Same, RAM only (no ratchet file) │
│ EnforceRatchets │ Reject identity-key ciphertext (opt-in, same as Python) │
│ SetRetainedRatchets / SetRatchetInter… │ Retention count and rotation interval │
│ RotateRatchets / CurrentRatchetPublic… │ Local rotation and announce public key │
└────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Link (T383838pkg/link)

┌─────────────────┬───────┬─────────────────┐
│ Status │ Value │ Meaning on Link │
├─────────────────┼───────┼─────────────────┤
│ StatusPending │ T3838380x00 │ Not established │
│ StatusHandshake │ T3838380x01 │ Handshake │
│ StatusActive │ T3838380x02 │ Ready │
│ StatusStale │ T3838380x03 │ Stale │
│ StatusClosed │ T3838380x04 │ Closed │
│ StatusFailed │ T3838380x05 │ Failed │
└─────────────────┴───────┴─────────────────┘

┌─────────────────────────────────────────────────┬──────────────────────────────────────────┐
│ Symbol │ Role │
├─────────────────────────────────────────────────┼──────────────────────────────────────────┤
│ T383838NewLink(dest, transport, iface, onEst, onClose) │ Outbound link object │
│ T383838Establish() error │ Initiator handshake │
│ T383838EstablishmentTimeout() │ Handshake wait used by the link watchdog │
│ T383838Teardown() │ Close │
│ T383838Identify(id) │ Prove local identity to peer │
│ Send / SendPacket / SendPacketWithContext │ Encrypted data │
│ T383838Request(path, data, timeout) │ Msgpack request (auto resource if large) │
│ T383838SendResource(res) │ Outbound resource transfer │
│ T383838GetChannel() │ Reliable channel over the link │
│ SetResourceStrategy │ AcceptNone / AcceptAll / AcceptApp │
│ SetResourceConcludedCallback │ T383838[]byte or IncomingResource │
│ GetRTT / idle timers / PHY stats │ Link health │
└─────────────────────────────────────────────────┴──────────────────────────────────────────┘

RequestReceipt

┌─────────────────────────────────────────┬────────────────────────────────────────────────────────┐
│ Method │ Role │
├─────────────────────────────────────────┼────────────────────────────────────────────────────────┤
│ T383838Concluded() │ Finished (success or failure) │
│ T383838GetStatus() │ StatusActive means response OK, StatusFailed means ti… │
│ T383838GetResponse() / T383838GetResponseValue() │ Bytes or decoded msgpack │
│ T383838GetMetadata() │ Resource response metadata │
│ T383838Progress() │ Bytes received / total for resource replies │
│ SetResponseCallback / SetFailedCallback │ Async completion │
└─────────────────────────────────────────┴────────────────────────────────────────────────────────┘

Do not confuse T383838RequestReceipt.GetStatus() with T383838Link.GetStatus(). Both reuse status byte constants with different meanings.

Resource (T383838pkg/resource)

┌───────────────────────────────────┬────────────────────────────────────────────────┐
│ Symbol │ Role │
├───────────────────────────────────┼────────────────────────────────────────────────┤
│ T383838New(data, autoCompress) │ T383838[]byte or seekable file │
│ T383838SetMetadata(map) │ Prepended msgpack metadata (Python-compatible) │
│ GetProgress / GetStatus / GetHash │ Transfer state │
│ PrepareOutboundForLink │ Called by T383838Link.SendResource │
└───────────────────────────────────┴────────────────────────────────────────────────┘

Statuses: StatusPending, StatusActive, StatusComplete, StatusFailed, StatusCancelled.

Transport (via T383838Node.Transport())

┌──────────────────────────────────────────┬───────────────────────────────────────────────────────┐
│ Method │ Role │
├──────────────────────────────────────────┼───────────────────────────────────────────────────────┤
│ T383838HasPath(hash) │ Cached route present │
│ T383838RequestPath(hash, iface, tag, recursive) │ Path request (throttled) │
│ HopsTo / NextHop / NextHopInterface │ Route inspection │
│ T383838FirstHopTimeout(hash) │ Next-hop airtime plus 6s (Python T383838get_first_hop_timeo… │
│ T383838PathResponseWindow(hash) │ Cold path wait from slowest online bitrate │
│ T383838SlowestOnlineBitrate() │ Lowest advertised bitrate of an online interface │
│ ExpirePath / PrepareFreshPathRequest │ Drop or refresh cache │
│ RegisterInterface / GetInterfaces │ Interface table │
│ RegisterDestination │ Usually automatic for In destinations │
│ SendPacket / HandlePacket │ Low-level inject (advanced) │
│ RegisterAnnounceHandler │ Observe announces │
└──────────────────────────────────────────┴───────────────────────────────────────────────────────┘

Avoid T383838transport.Destination and T383838transport.Link placeholder types. Use T383838destination.Destination and T383838link.Link.

Packet (T383838pkg/packet)

┌───────────────────────────┬───────────────────────────────────────────────────┐
│ Symbol │ Role │
├───────────────────────────┼───────────────────────────────────────────────────┤
│ T383838MTU │ 500 │
│ NewPacket / Pack / Unpack │ Wire encode/decode │
│ PacketReceipt │ Delivery proofs for data packets │
│ Context constants │ ContextRequest, ContextResource, link contexts, … │
└───────────────────────────┴───────────────────────────────────────────────────┘

Config (T383838pkg/reticulumconfig, T383838pkg/common)

┌──────────────────────────────────────────────────┬───────────────────────────────────────┐
│ Function │ Role │
├──────────────────────────────────────────────────┼───────────────────────────────────────┤
│ T383838InitConfig() │ Load or create T383838~/.reticulum-go/config │
│ T383838LoadConfig(path) │ Parse INI (unknown keys ignored) │
│ SaveConfig / DefaultConfig / CreateDefaultConfig │ Persist defaults │
└──────────────────────────────────────────────────┴───────────────────────────────────────┘

Important ReticulumConfig fields: EnableTransport, ShareInstance, SharedInstanceType, ports, RPCKey, Interfaces, EnableControlAPI, InMemoryPathTable, InMemoryStorage, WatchInterfaces, DiscoverInterfaces, BackboneIO.

Default config directory is T383838~/.reticulum-go, not T383838~/.reticulum.

Python to Go map

┌──────────────────────────────────────────────────┬───────────────────────────────────────────────┐
│ Python │ Go │
├──────────────────────────────────────────────────┼───────────────────────────────────────────────┤
│ T383838RNS.Reticulum(configdir=...) │ T383838reticulumconfig.LoadConfig + T383838node.New + Start │
│ T383838RNS.Identity() │ T383838identity.New() │
│ T383838Identity.from_file / to_file │ FromFile / ToFile │
│ T383838Identity.recall(hash) │ T383838identity.Recall(hash) │
│ T383838Destination(identity, IN, SINGLE, app, *aspects) │ T383838destination.New(id, destination.In, destinat… │
│ T383838Destination(..., OUT, ...) │ T383838destination.Out or FromHash for known peers │
│ T383838destination.announce() │ T383838dest.Announce(false, nil, nil) │
│ T383838destination.set_link_established_callback │ SetLinkEstablishedCallback (T383838func(any)) │
│ T383838destination.register_request_handler │ RegisterRequestHandler / RegisterRequestHand… │
│ T383838RNS.Link(destination) │ T383838link.NewLink + Establish │
│ T383838link.establishment_timeout │ T383838l.EstablishmentTimeout() │
│ T383838link.identify(identity) │ T383838l.Identify(id) │
│ T383838link.request(path, data=...) │ T383838l.Request(path, data, timeout) │
│ T383838RNS.Resource(data, link, metadata=...) │ T383838resource.New + SetMetadata + T383838l.SendResource │
│ T383838RNS.Transport.has_path / request_path │ T383838tr.HasPath / T383838tr.RequestPath │
│ T383838RNS.Reticulum.get_first_hop_timeout │ T383838tr.FirstHopTimeout (use T383838rnsutil.FirstHopTime… │
│ Shared instance master │ First T383838share_instance = yes process (daemon o… │
│ T383838~/.reticulum │ T383838~/.reticulum-go │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┘

Concurrency and callbacks

┌───────────────────────────────────────┬──────────────────────────────────────────────────────────┐
│ Component │ Rule │
├───────────────────────────────────────┼──────────────────────────────────────────────────────────┤
│ Transport / interfaces │ Packet handlers run on interface or transport goroutines │
│ Destination / link callbacks │ May fire concurrently. Return quickly. Do heavy work in… │
│ T383838Link.Request receipts │ Timeout and response callbacks run in separate goroutin… │
│ Same Link │ Do not call Establish, Teardown, and Request concurrent… │
│ T383838Node.ReloadInterfaces / network hooks │ Serialized by an internal mutex │
│ Identities / destinations │ Internally mutex-protected. Still treat callbacks as re… │
└───────────────────────────────────────┴──────────────────────────────────────────────────────────┘

Python RNS is largely single-threaded asyncio. Go is multi-threaded by default. Design for that.

Errors and empty results

┌────────────────────────────────────────┬─────────────────────────────────────────────────────────┐
│ Situation │ Typical signal │
├────────────────────────────────────────┼─────────────────────────────────────────────────────────┤
│ No path yet │ HasPath false. Call RequestPath and wait │
│ Link not ready │ Establish error or T383838GetStatus() != StatusActive │
│ Request timeout │ RequestReceipt status StatusFailed │
│ Recall before announce │ T383838identity.Recall error. Wait for announce or seed known… │
│ Shared instance auth failure │ RPC dial / auth error. Align rpc_key or transport iden… │
│ Hardware-bound identity without signer │ ErrHardwareBoundSignerRequired │
└────────────────────────────────────────┴─────────────────────────────────────────────────────────┘

Other API surfaces

┌──────────────────────────────────────────┬───────────────────────────────────────────────────────┐
│ Surface │ Document │
├──────────────────────────────────────────┼───────────────────────────────────────────────────────┤
│ Localhost JSON and WebSocket │ Control API
• Package map
• Embedding and WebAssembly
• Compatibility
• Python RNS API reference (wire and semantic authority)

Served by rngit 1.5.2 - Generated in 0.03s